home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / c / pmm / doku / thirdpartytools / fd2libwos.doc < prev    next >
Text File  |  1999-06-14  |  5KB  |  144 lines
  1. fd2libWOS by Frank Wille / Volker Barthelmann / Johnny Tevessen
  2.  
  3.  
  4. INTRODUCTION
  5.  
  6.     fd2libWOS takes .fd-files as input and generates assembler source to
  7.     create a library with stubs to call the functions (including stubs
  8.     for varargs functions).
  9.  
  10.  
  11. LEGAL
  12.  
  13.     fd2libWOS is public domain.
  14.  
  15.  
  16. USAGE
  17.  
  18.     Usage : fd2libWOS [-sd] [-l] [-r2] [-nv] [-base <name>] [-o <dir>]
  19.                       [-of <format>] [-d] [-?|--help] [files/pattern]
  20.  
  21.       -sd  : Use small data model (else large data model)
  22.              Not yet supported.
  23.       -l   : First argument (r3) is library base
  24.       -r2  : PPC-only library uses r2 as base register (##abi PPC2)
  25.       -nv  : No varargs logic - ...A and ...TagList will not be detected
  26.       -base: Overwrites library base name (##base)
  27.       -o   : Specify directory to store source files in
  28.       -of  : C printf style output format to generate compiling
  29.              script. Three `%s' are replaced with output file name
  30.       -d   : Turn on debugging/verbose mode
  31.       -?   : Show help/version and quit
  32.     files  : FD files to convert, defaults to stdin
  33.  
  34.     Commandline is parsed left-to-right. So specifying
  35.  
  36.     > fd2libwos alib_lib.fd -sd blib_lib.fd
  37.  
  38.     will result in alib created using large data model.
  39.  
  40.     There may also be a -prof option in future, but it's not yet
  41.     implemented.
  42.  
  43.     fd2libwos will process all the .fd-files specified at the command line
  44.     (not specifying any filename results in fd2libwos using stdin (console)
  45.     as input) and will generate an assembler source for each library
  46.     function as functionname.s and a file containing all the library
  47.     vector offsets as libname_lvo.s.
  48.  
  49.     Files are placed in the current directory. Specify an alternative
  50.     destination using the `-o <dir>' option.
  51.  
  52.  
  53. GENERATED CODE
  54.  
  55.     fd2libWOS creates code to be assembled with Frank Wille's pasm (use
  56.     option -F2 for EHF). The generated stubs are compatible with H&P's
  57.     PowerOpen-ABI. vlink is recommended for linking the stubs, because
  58.     the "@_xxx" symbols have to be created on demand.
  59.  
  60.  
  61. VARARGS
  62.  
  63.     Some functions take a pointer to a list of arguments as the last
  64.     argument. fd2libwos has a hardcoded list of such function and creates
  65.     additional stubs that can be called with a variable number of arguments
  66.     from C (e.g. OpenWindowTagList and OpenWindowTags).
  67.  
  68.     If you want to extend this list, you have to add the name of the
  69.     function and the name of the varargs function to the file vargs.h
  70.     and recompile fd2libwos.
  71.  
  72.     Fd2libwos also tries to recognize functions that might have varargs
  73.     automatically. It scans for `TagList' and `A' postfixes and sub-
  74.     stitutes them with `Tags' or `'. `A's are only suggested to be varargs
  75.     if the letter right before is lowercase.
  76.  
  77.     You may turn off automatic recognition by specifying `-nv'.
  78.  
  79.  
  80. GOODIES
  81.  
  82.     `-of <string>' allows you to get runtime output. You may use this
  83.     feature to show fd2libwos's progress or to create batch files for post-
  84.     processing fd2libwos's output. `%s' is substituted by the output asm file
  85.     just processed. E.g.:
  86.  
  87.     > fd2libWOS -of "pasm -F2 %s" fd:dos_lib.fd >batchfile
  88.     > execute batchfile
  89.  
  90.     will process dos' functions and then compile them straight-forward.
  91.  
  92.     You may use `%s' upto three times in the format string. C like jokes
  93.     like `%30s' to show the file's name right-aligned are also allowed.
  94.  
  95.  
  96. CREATING LIBRARIES
  97.  
  98.     If you want to create a library from some .fd-files proceed like this:
  99.  
  100.     > delete T:#?.(s|o) quiet
  101.     > fd2libWOS -o T: <all the .fd-files you want>
  102.  
  103.     (copying pasm to ram: now may speed up the process)
  104.  
  105.     > vc +warpos -c T:#?.s
  106.     > join as <name of resulting lib> T:#?.o
  107.     > delete T:#?.(s|o)
  108.  
  109.  
  110. MakeALIB.script
  111.  
  112.     This is a small but smart script which will create an amiga.lib
  113.     in T:. It will delete files from T: before and assumes nothing is
  114.     written to T: while it is running.
  115.  
  116.     You have to assign FD: to a directory that contains the .fd-files for
  117.     the Amiga shared libraries and cd into the libsrc/AmigaLib directory
  118.     and start it from there. Otherwise you will get an error.
  119.  
  120.     It will then create all library stubs and LVOs with fd2libWOS (this
  121.     will result in many many small files in T: which will be assembled by
  122.     pasm - so having pasm in RAM: will speed it up quite a lot).
  123.  
  124.     Then the support routines in libsrc/AmigaLib will be compiled/assembled
  125.     and the resulting object files will be put in T:, too. You must have
  126.     the C= includes.
  127.  
  128.     The support routines are taken from libnix and have been changed a bit
  129.     to work with vbcc. I have not tested them and several support routines
  130.     from the original amiga.lib are missing.
  131.  
  132.     The whole process may take quite some time and a few MB space in T:
  133.     The resulting amiga.lib should be free from any copyright and is a
  134.     rather good (but not complete) replacement for the original amiga.lib.
  135.  
  136.     If everything went right you will be asked whether you want to have the
  137.     library installed to vlibwos:. Type <y> or do so manually if you don't
  138.     trust my script. :-)
  139.  
  140.  
  141. Frank Wille                                             frank@phoenix.owl.de
  142. Volker Barthelmann                                      volker@vb.franken.de
  143. Johnny Tevessen                                          j.tevessen@line.org
  144.